home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / FROMUTS / TRASH / !Trash / !ReadMe next >
Text File  |  1990-07-11  |  16KB  |  358 lines
  1. >$.!Trash.!ReadMe
  2.  
  3.                   Documentation for Trash Can Module V1.30
  4.                   ----------------------------------------
  5.  
  6. *********************************** Notice ******************************
  7. *                                                                       *
  8. *  The documentation, source, binary and resources for the Trash Can,   *
  9. *  whilst the copyright of Richard K. Lloyd, may be freely distributed  *
  10. *          provided that this Notice is not altered in any way.         *
  11. *                                                                       *
  12. *************************************************************************
  13.  
  14. New features present in V1.30
  15. -----------------------------
  16.  
  17. * New 'Immediate' menu added - allows trash to be deleted immediately
  18.   if this option is ticked. In other words, no temporary Trash directory
  19.   is needed and files will be completely deleted as soon as they are
  20.   dragged onto the Trash Can menu. If the option is not ticked, then
  21.   files are renamed into the temporary Trash directory as usual.
  22.  
  23. * New 'Warning' menu added - if this option is ticked, then the border
  24.   colour turns to bright red if a file is being dragged onto the Trash Can
  25.   icon and the 'Immediate' option is ticked or if the 'Empty Trash' menu option
  26.   is highlighted whilst the 'Immediate' option is turned off.
  27.  
  28. * New 'Animation' menu added - a Trash Van will drive along the icon bar and
  29.   pick up the trash if this option is ticked. This will happen if the
  30.   Empty Trash menu option is selected or if a file is dragged on the Trash
  31.   Can icon whilst the 'Immediate' option is ticked. Many thanks to Gary
  32.   Bartlett for the idea and the sprite definitions for the cute Trash Van.
  33.   Apologies to everyone (except ARM3 owners) about the flickering - it's a
  34.   side-effect of being forced to use Wimp_SpriteOp rather than the faster
  35.   OS_SpriteOp. NOTE: The animation works only in 16-colour MODEs.
  36.   Many thanks to Gary Bartlett for the Trash Van inspiration and sprites.
  37.  
  38. * Bug with Info Window workspace fixed - a second loading of !Trash (which
  39.   shuts down the first task automatically) or a Temporary Quit followed by
  40.   a Desktop exit and re-entry will force the Template for the Info window
  41.   to be reloaded.
  42.  
  43. How to install the Trash Can
  44. ----------------------------
  45.  
  46. The Trash Can module is supplied with the following files:
  47.  
  48. !Trash            : The application dir.
  49. !Trash.!ReadMe    : This file.
  50. !Trash.!Run       : An Obey file to set up the Trash Can (may need editing).
  51. !Trash.!RunImage  : The Trash Can Module. Do NOT run this on its own.
  52. !Trash.!Sprites   : Three trash can sprites...
  53.                              !trash : Used in the Filer window
  54.                     !trash1/!trash2 : Used on the icon bar
  55.                     Do NOT rename any of these sprites !
  56. !Trash.Templates  : The definition, created by !FormEd, for the Info window.
  57. !Trash.TrashSrc   : The heavily annotated source code.
  58. !Trash.VanSprites : Six trash van sprites...
  59.                     vanlft1..vanlft3 : 3-stage animation of left-pointing van
  60.                     vanrgt1..vanrgt3 : Ditto, but for right-pointing van
  61.  
  62. The Trash Can Module has been designed to run from the Desktop by double-
  63. clicking on the !Trash directory and, because it is a service utility, it
  64. installs an icon on the left-hand side of the icon bar. Attempts to run it
  65. outside the Desktop (by typing *!Trash) will install the Trash Can module
  66. with a message informing you to enter the Desktop afterwards with a *Desktop
  67. command to properly start up the utility.
  68.  
  69. Setting up the Trash$Dir directory
  70. ----------------------------------
  71.  
  72. The environmental variable Trash$Dir is read (and deliberately re-read
  73. frequently during the module's life) - this should be set in the !Run file
  74. to point to a directory where the trash is to be placed. If the directory
  75. does not exist, then it will created when the first trashing or viewing of
  76. the trash contents takes place.
  77.  
  78. The recommended settings are:
  79.  
  80. For hard disk owners:  Set Trash$Dir <Obey$Dir>.Trash
  81. For floppy    owners:  Set Trash$Dir <Obey$Dir>.Trash
  82.                   OR   Set Trash$Dir adfs:$.Trash
  83.                   OR   Set Trash$Dir adfs:$.!Trash.Trash
  84.  
  85. Whatever you decide, Trash$Dir (after environmental variable expansion) MUST
  86. contain the filing system name (usually adfs:) and at least ONE full-stop
  87. (directory separator to give it its full title). Please note that there is
  88. now a second environmental variable called TrashWork$Dir declared in the !Run
  89. file. This is used by the Trash Can Module to locate the sprites and template
  90. files it needs.
  91.  
  92. Problems with floppy disc-based Trash Can
  93. -----------------------------------------
  94.  
  95. If you specify <Obey$Dir> in the Trash$Dir variable, then the disk with the
  96. !Trash directory on it MUST be in a drive at all times. If it isn't, then
  97. the Filer will prompt you for it VERY frequently...
  98.    If you decide to rename the floppy disk (*NameDisc or whatever) that
  99. contains the Trash$Dir directory, then you should restart the Trash Can by
  100. double-clicking on !Trash again to get the new disk name read in.
  101.    One tip for people who are panicking - define Trash$Dir as the string
  102. 'adfs:$.!Trash.Trash' (the third alternative mentioned above) and copy the
  103. !Trash directory (without the TrashSrc file !) onto all your workdisks.
  104.  
  105. If you are still annoyed at having to fumble for disks, you can now enable
  106. a new 'Immediate' option which will bypass the Trash$Dir directory and
  107. immediately delete files that are dragged onto the Trash Can icon. This
  108. is not recommended for hard disk owners unless you are short of hard disk
  109. space.
  110.  
  111. Using the RAM Disk
  112. ------------------
  113.  
  114. Yes, it is possible to use the RAM Disk to store trashed files, but this has
  115. some snags:
  116.  
  117. 1. Files will always be COPIED/DELETED (assuming you are trashing an ADFS
  118.    file) rather than renamed - making the trashing a lot slower process.
  119.  
  120. 2. It's likely that the size of your RAM disc will not be large enough to
  121.    trash many files (especially compared to a hard disk).
  122.  
  123. 3. The biggest problem: A hard reset or a power off will lose the contents
  124.    of the RAM disk - and hence all the files you trashed will be irrecoverable.
  125.  
  126. There are only two advantages as far as I can see:
  127.  
  128. 1. Floppy owners won't have to keep the disk containing Trash$Dir in one
  129.    of the drives all the time.
  130.  
  131. 2. Emptying the trash is incredibly fast.
  132.  
  133. If, after all this, you still want to use the RAM Disk, change the Trash$Dir
  134. line in the !Run file to:
  135.  
  136. Set Trash$Dir RAM:$.Trash
  137.  
  138. Make sure you have a fairly big RAMFsSize setting too (128K recommended).
  139.  
  140. The Trash Can Icon Bar Icon (now known as the 'Trash Can Icon')
  141. ---------------------------
  142.  
  143. There are TWO possible trash can icons depending on the state of the contents
  144. of the Trash Can :
  145.  
  146. If Trash$Dir is empty or doesn't exist, then the thin icon (!trash1) is used.
  147. If Trash$Dir is not empty, then the fat icon (!trash2) is used.
  148.  
  149. The icon is updated during any *SAVE,*RENAME,*DELETE,*WIPE,*COPY,*CREATE or
  150. file opening for output, which should mean that it reflects the current
  151. contents of Trash$Dir accurately.
  152.  
  153. Trashing Files
  154. --------------
  155.  
  156. To trash a file, select it using the left button (right button if more than
  157. one) and drag it over the trash can icon using the left button. If the
  158. 'Warning' and 'Immediate' options are both enabled, then the border will turn
  159. red whilst the drag is over the Trash Can icon as a warning that a button
  160. release will immediately and irretrieveably delete the dragged files.
  161.  
  162. If the 'Immediate' option is disabled, the Trash Can Module will attempt a
  163. *Rename for speed. If this fails (and you're not trying to be clever by
  164. dragging the Trash$Dir directory onto the trash can icon !), then a
  165. *Copy/*Delete mechanism is used instead. Any identically named files in
  166. Trash$Dir will be overwritten.
  167.  
  168. Lucky owners of V2.xx of Spark will be able to drag compressed files from
  169. a Spark Archive window onto the Trash Can icon. The files will be decompressed
  170. (to a temporary Wimp$Scrap file), moved to Trash$Dir and then deleted from the
  171. original Archive. Please note: Due to the use of the Wimp$Scrap system,
  172. an Archived directory will appear as an ARCHIVE FILE in Trash$Dir when it is
  173. dragged onto the Trash Can.
  174. PLEASE NOTE: (1) For this facility to work, the Trash Can Utility must be
  175.                  installed BEFORE Spark.
  176.              (2) Beta-test copies of Spark 2.00 do not behave properly with
  177.                  this facility (they have a tendency to fatally crash).
  178.                  Use the proper commercial release of Spark 2.00.
  179.  
  180. When you want to empty the contents of the Trash Can, select the 'Empty Trash'
  181. memu item (see below). If the emptying of the Trash Can or the trashing of
  182. files fails (e.g. write-protected disk, disk fault), then a standard error
  183. dialogue box will appear (OK = retry, Cancel = abort). If the operations are
  184. OK, but are taking longer than 1 second, then an Hourglass pointer will appear.
  185.  
  186. The Trash Can Window
  187. --------------------
  188.  
  189. When the trash can icon is clicked on using the left or right buttons, a
  190. Filer window is opened to show the current contents of Trash$Dir. All normal
  191. Filer operations can be performed on this window, which makes it far more
  192. flexible than all other Trash Can Windows I've seen to date (he says
  193. modestly !). The Trash Can Window CANNOT be viewed whilst the Immediate option
  194. is enabled.
  195.  
  196. The Trash Can Menu
  197. ------------------
  198.  
  199. When the trash can icon is clicked on using the middle button, a pop-up menu
  200. appears as follows:
  201.  
  202.     Info      =>
  203.  
  204.     This is a version/author message displayed as a standard Info window,
  205.     which can now be dragged around the screen for no apparent reason.
  206.     It was created by !FormEd and saved in the Templates file.
  207.  
  208.     Immediate
  209.  
  210.     If this option is ticked, then any files dragged onto the Trash Can icon
  211.     will be immediately and irretrieveably deleted. If is not ticked, then
  212.     the files will be *Renamed (or *Copied/*Deleted) into the Trash$Dir
  213.     directory instead. The Immediate option state is saved in Bit 0 of
  214.     CMOS RAM location 38.
  215.  
  216.     Warning
  217.  
  218.     If this (and the 'Immediate' option) option is ticked, then the border
  219.     will turn red whilst the pointer (during a file drag) is situated over the
  220.     Trash Can icon. The border will also turn red if the 'Immediate' option is
  221.     disabled and the 'Empty Trash' option is highlighted. These signal
  222.     'dangerous' operations for the unwary... The Warning option state is saved
  223.     in Bit 1 of CMOS RAM location 38.
  224.  
  225.     Animation
  226.  
  227.     If this option is ticked, then a simple Trash Van animation occurs on
  228.     the icon bar whenever 'Empty Trash' is selected or when files are dragged
  229.     onto the Trash Can icon with the 'Immediate' option enabled. The Animation
  230.     option state is saved in Bit 2 of CMOS RAM location 38. Many thanks to
  231.     Gary Bartlett for the inspiration and the sprite definitions !
  232.     NOTE: The animation only works in 16-colour MODEs.
  233.  
  234.     Empty Trash
  235.  
  236.     This will appear 'shaded' (normally grey) if either Trash$Dir is empty or
  237.     if the Immediate option is enabled, but solid if it contains any files and
  238.     the Immediate option is disabled. THIS IS THE ONLY WAY TO CLEAR Trash$Dir
  239.     using the Trash Can Module - direct drags from the Trash Can Window
  240.     onto the trash can icon DO NOT delete the files (in fact, they get
  241.     renamed onto themselves !).
  242.  
  243.     Quit      =>
  244.     
  245.     This points to a sub-menu which has two options:
  246.  
  247.     Quit      => Temporary
  248.  
  249.     This removes the Trash Can utility from the Desktop, but the module still
  250.     remains in memory. You can, of course, use the Task Manager to Quit the
  251.     Trash Can Module in an identical way. To reactivate, use the Task Manager's
  252.     'New Task' to type *Desktop_TrashCan (you can use the f12 mechanism also).
  253.  
  254.     Quit      => Permanent    (this is the default if Quit is selected
  255.                                on the MAIN menu)
  256.  
  257.     This not only removes the Trash Can Desktop utility but also kills the
  258.     Trash Can module and unsets the two environmental variables used by it
  259.     (Trash$Dir and TrashWork$Dir). This is the recommended way to completely
  260.     remove the Trash Can program from the system.
  261.  
  262. Recovering trashed files
  263. ------------------------
  264.  
  265. To recover files that have been trashed with the 'Immediate' option disabled
  266. (assuming that you haven't emptied the trash yet), open the Trash Can Window
  267. (left or right button) and SHIFT-drag the files from that window onto another
  268. open Filer Window. Remember that holding down SHIFT during a file drag deletes
  269. the files in the source window, which is what you want.
  270.  
  271. What can the Trash Can Module survive ?
  272. ---------------------------------------
  273.  
  274. Unlike BASIC versions of the Trash Can, this module can survive:
  275.  
  276. 1.  Complete wipe of application workspace (e.g. *InitStore 0).
  277. 2.  Exit from and re-entry to the Desktop.
  278. 3.  A soft reset.
  279. 4.  *RMReInit TrashCan.             } Normally issued
  280. 5.  *RMTidy.                        } outside the Desktop
  281. 6.  Various run-time errors (e.g. missing sprites/templates, not enough RMA).
  282. 7.  *Unset Trash$Dir.
  283. 8.  Setting (the expanded) Trash$Dir longer than 63 characters.
  284. 9.  The Trash Can Temporary Quit option.
  285. 10. Shutdown of it via the Task Manager window.
  286.  
  287. Please note that 2, 4, 5, 9 and 10 above will cause a reload of the Trash Can
  288. sprite and template files upon re-entry to the Desktop. If you are inside the
  289. Desktop, the Trash Can can be restarted by issuing the *Desktop_TrashCan
  290. command after any problems have been fixed.
  291.  
  292. It cannot survive:
  293.  
  294. 1. A hard reset.
  295. 2. *RMKill TrashCan.
  296. 3. *RMClear.
  297. 4. The Trash Can Permanent Quit Option.
  298. 5. Power off and on (obvious !).
  299.  
  300. Conclusion
  301. ----------
  302.  
  303. Well, that's it. My first multi-tasking RISC OS module. The Trash Can icons
  304. were based (as was the idea of storing the files in a Trash directory) on
  305. the Macintosh icons (ResEdit was rather handy...). At least my module doesn't
  306. empty the trash when you start a new application or eject the disk (a
  307. disgraceful oversight on the part of Apple) ! Have you seen a better Trash Can
  308. program ? If so, let me know because my disks are full of them (although you
  309. can now 'trash' all other Trash Cans apart from mine !!)...
  310.  
  311. Revision History
  312. ----------------
  313.  
  314. Supplied in the form of comments at the start of the source code. New features
  315. in this latest release are described at the top of this document.
  316.  
  317. Future Enhancements
  318. -------------------
  319.  
  320. * Add a 'stationary' Trash Van sprite so that it doesn't disappear during the
  321.   actually trash emptying.
  322.  
  323. * Stop the Trash Van from flickering ! It flickers if I use Wimp_SpriteOp,
  324.   but doesn't if I just use OS_SpriteOp... Unfortunately, I can't use the
  325.   latter in a Wimp program :-(
  326.  
  327. * Stop the border from flashing red (when the Warning option is enabled) when
  328.   you simply click on the Trash Can icon rather than drag a file onto it.
  329.  
  330. * Find a way to ID Spark 2 if it has been installed BEFORE the Trash Can
  331.   program has been run.
  332.  
  333. * Get an updated Spark 2 (time to register methinks !) from David Pilling
  334.   to make sure the Spark archive -> Trash Can drag code works with his latest
  335.   versions...
  336.  
  337. Estimated Date of Release of V1.40
  338. ----------------------------------
  339.  
  340. Approximately September or October 1990, but no guarantees... I will not
  341. release V1.40 until I get an up-to-date copy of Spark 2 for extensive
  342. testing with the Trash Can module.
  343.  
  344. A Plea From The Author
  345. ----------------------
  346.  
  347. If you make some USEFUL changes to the source or fix any bugs, can you please
  348. send me those changes to the following address:
  349.  
  350. Snail Mail                   JANET e-mail
  351. ----------                   ------------
  352.  
  353. Richard K. Lloyd,            rkl@uk.ac.liv.cs.mva
  354. 1, Banks Road,
  355. Lower Heswall,
  356. Wirral,
  357. Merseyside. L60 9JS
  358.